#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
#  __doc__.py : Document in reST format of gui module.
#
# Copyleft (C) 2014 - huhamhire <me@huhamhire.com>
# =====================================================================
# Licensed under the GNU General Public License, version 3. You should
# have received a copy of the GNU General Public License along with
# this program. If not, see <http://www.gnu.org/licenses/>.
# =====================================================================
"""
.. _gui-module:

Graphical User Interface (GUI)
==============================

The following sections describe the objects and methods from the Graphical
User Interface (GUI) module of huhamhire-hosts HostsUtil. The methods to make
GUI here are based on `PyQT4 <http://pyqt.sourceforge.net/Docs/PyQt4/>`_.


HostsUtil(GUI)
--------------
.. autoclass:: gui.hostsutil.HostsUtil
    :members:

    .. automethod:: gui.hostsutil.HostsUtil.__del__


QDialogSlots
------------
.. autoclass:: gui.qdialog_slots.QDialogSlots
    :members:

    .. automethod:: gui.qdialog_slots.QDialogSlots.__init__


LangUtil
--------
.. autoclass:: gui.language.LangUtil
    :members:


QDialogDaemon
-------------
.. autoclass:: gui.qdialog_d.QDialogDaemon
    :members:


QDialogUI
---------
.. autoclass:: gui.qdialog_ui.QDialogUI
    :members:

    .. automethod:: gui.qdialog_ui.QDialogUI.__init__


QSubChkConnection
-----------------
.. autoclass:: gui._checkconn.QSubChkConnection
    :members:

    .. automethod:: gui._checkconn.QSubChkConnection.__init__


QSubChkUpdate
-------------
.. autoclass:: gui._checkupdate.QSubChkUpdate
    :members:

    .. automethod:: gui._checkupdate.QSubChkUpdate.__init__


QSubFetchUpdate
---------------
.. autoclass:: gui._update.QSubFetchUpdate
    :members:

    .. automethod:: gui._update.QSubFetchUpdate.__init__


QSubMakeHosts
-------------
.. autoclass:: gui._make.QSubMakeHosts
    :members:

    .. automethod:: gui._make.QSubMakeHosts.__init__


.. _qt-resource-modules:

Resource Modules
----------------
All Qt Project files and resource files are convented into python Resource
Modules in order to be used by `Hosts Setup Utility`. Including:

* util_ui.py: :class:`~gui.util_ui.Ui_Util` class organizing layout of the
  main dialog for `Hosts Setup Utility`. This file is translated from the UI
  project file `util_ui.ui`.

  .. seealso:: `util_ui.ui` in :ref:`QT Project Files <qt-project-files>`.

* util_rc.py: Images resources used by the main dialog.

* style_rc.py: Images resources used by the default `Qt Stylesheet`.

  .. seealso:: :ref:`QT Stylesheet <qt-stylesheet>`.

.. seealso:: `_pyuic4.py` in :ref:`QT Project Scripts <qt-project-scripts>`.


.. _qt-project-files:

QT Project Files
----------------
Qt Project Files and Qt resources files used to design the Qt user interface
are provided in the "`gui/pyqt/`" directory, including:

* util.pro: QT Project file containing configuration of current project.

* util.qrc: Resource file for main dialog generated by `Qt Designer`.

* style.qrc: Resource file for the default `Qt Style Sheet` generated by
  `Qt Designer`.

  .. seealso:: :ref:`QT Stylesheet <qt-stylesheet>`.

* util_ui.ui: UI project file for the main dialog designed with
  `Qt designer`.

.. seealso::
    `Qt Designer <http://qt-project.org/doc/qt-4.8/designer-manual.html>`_.


.. _qt-project-scripts:

QT Project Scripts
------------------
Scripts to help managing the Qt project are also provided in the "`gui/pyqt/`"
directory:

* _pylupdate4.py: Contains tools to update the language files for UI.

  .. note:: This script would parse files declared as `SOURCES` in the Qt
      project file (`gui/pyqt/util.pro`), and generate/update language files
      declared as `TRANSLATIONS` in the Qt project file.

  .. seealso:: :ref:`Language Files <qt-language-files>`.

* _pyuic4.py: Tools used to update the `UI module` and `Resource Modules`
  from `UI file` and `Resources Files` designed with `Qt designer`.

  .. seealso:: :ref:`Resource Modules <qt-resource-modules>`.


.. _qt-language-files:

Language Files
--------------
Since this GUI module of `Hosts Setup Utility` is based on :mod:`PyQt4`,
it is very easy to internationalization this utility with the ways Qt
provided.

The `Qt Language Files` are stored in "`gui/lang/`" directory with file
suffixes "`.qm`" and "`.ts`".

.. note:: **File Types**

    `Hosts Setup Utility` makes use of two kinds of files:

    * TS: `translation source files`
      are human-readable XML files containing source phrases and their
      translations. These files are usually created and updated by `lupdate`
      and are specific to an application.

    * QM: `Qt message files`
      are binary files that contain translations used by an application at
      run-time. These files are generated by lrelease, but can also be
      generated by `Qt Linguist`.

.. note:: You can use `_pylupdate4.py` provided in "`gui/pyqt/`" directory to
    generate/update `TS` files with the Qt project file. And then use
    `Qt Linguist` to make a `QM` file.

    .. seealso:: `_pylupdate4.py` in
        :ref:`QT Project Scripts<qt-project-scripts>`.

    .. seealso:: `Qt Linguist
        <http://qt-project.org/doc/qt-4.8/linguist-translators.html>`_.


.. _qt-stylesheet:

QT Stylesheet
-------------
With the GUI module of `Hosts Setup Utility` is based on :mod:`PyQt4`, Qt
style sheets are also supported to customize the appearance of GUI widgets.

The `Qt Style Sheets` are stored in "`gui/theme/`" directory with file suffix
"`.qss`".

You can create yourown Qt style sheet and use it in method
:meth:`~gui.qdialog_ui.QDialogUI.set_stylesheet` to customize new appearance
of GUI widgets.

.. seealso:: Method :meth:`~gui.qdialog_ui.QDialogUI.set_stylesheet` in
    :class:`~gui.qdialog_ui.QDialogUI` class.

.. note:: Qt Style Sheets are a powerful mechanism that allows you to
    customize the appearance of widgets, in addition to what is already
    possible by subclassing QStyle. The concepts, terminology, and syntax
    of Qt Style Sheets are heavily inspired by HTML Cascading Style Sheets
    (CSS) but adapted to the world of widgets.

    .. seealso::
        `QT Stylesheet <http://qt-project.org/doc/qt-4.8/stylesheet.html>`_.
"""